<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>插入文档到集合中</title>

 </head>
 <body><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="mongocollection.group.html">MongoCollection::group</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="mongocollection.remove.html">MongoCollection::remove</a></div>
 <div class="up"><a href="class.mongocollection.html">MongoCollection</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mongocollection.insert" class="refentry">
 <div class="refnamediv">
  <h1 class="refname">MongoCollection::insert</h1>
  <p class="verinfo">(PECL mongo &gt;=0.9.0)</p><p class="refpurpose"><span class="refname">MongoCollection::insert</span> &mdash; <span class="dc-title">插入文档到集合中</span></p>

 </div>

 <div class="refsect1 description" id="refsect1-mongocollection.insert-description">
  <h3 class="title">说明</h3>
  <div class="methodsynopsis dc-description">
   <span class="modifier">public</span> <span class="type"><span class="type bool|array">bool|array</span></span> <span class="methodname"><strong>MongoCollection::insert</strong></span>
    ( <span class="methodparam"><span class="type"><span class="type array|object">array|object</span></span> <code class="parameter">$a</code></span>
   [, <span class="methodparam"><span class="type">array</span> <code class="parameter">$options</code><span class="initializer"> = array()</span></span>
  ] )</div>

  <p class="para rdfs-comment">
   发送到数据库的所有字符串必须是 UTF-8 的。如果有字符串不是 UTF-8，将会抛出 
   <a href="class.mongoexception.html" class="classname">MongoException</a> 异常。
   要插入（或者查询）一个非 UTF-8 的字符串，请使用 <a href="class.mongobindata.html" class="classname">MongoBinData</a>。
  </p>
 </div>


 <div class="refsect1 parameters" id="refsect1-mongocollection.insert-parameters">
  <h3 class="title">参数</h3>
  <p class="para">
   <dl>

    
     <dt>

      <em><code class="parameter">a</code></em>
     </dt>

     <dd>

      <p class="para">
       一个数组或对象。如果使用的是一个对象，它不能有 protected 或
       private 的属性。
      </p>
      <blockquote class="note"><p><strong class="note">Note</strong>: 
       <p class="para">
        如果参数不具有 <em>_id</em> 键或属性，
        将会创建一个新的 <a href="class.mongoid.html" class="classname">MongoId</a> 实例，并赋值给它。
        这种特殊行为不意味着参数是传引用的。
       </p>
      </p></blockquote>
     </dd>

    
    
     <dt>

      <em><code class="parameter">options</code></em>
     </dt>

     <dd>

      <p class="para">
       插入的选项。
       <ul class="itemizedlist">
        <li class="listitem"><p class="para"><em>&quot;w&quot;</em></p><p class="para">See <a href="mongo.writeconcerns.html" class="link">WriteConcerns</a>. The default value for <a href="class.mongoclient.html" class="classname">MongoClient</a> is <em>1</em>.</p></li>
        <li class="listitem"><p class="para"><em>&quot;fsync&quot;</em></p><p class="para">Boolean, defaults to <strong><code>FALSE</code></strong>. Forces the insert to be synced to disk before returning success. If <strong><code>TRUE</code></strong>, an acknowledged insert is implied and will override setting <em>w</em> to <em>0</em>.</p></li>
        <li class="listitem"><p class="para"><em>&quot;timeout&quot;</em></p><p class="para">Integer, defaults to <em>MongoCursor::$timeout</em>.  If &quot;safe&quot; is set, this sets how long (in milliseconds) for the client to wait for a database response.  If the database does not respond within the timeout period, a <a href="class.mongocursortimeoutexception.html" class="classname">MongoCursorTimeoutException</a> will be thrown.</p></li>
        <li class="listitem"><p class="para"><em>&quot;safe&quot;</em></p><p class="para"><em class="emphasis">Deprecated</em>. Please use the <a href="mongo.writeconcerns.html" class="link">WriteConcern</a> <em>w</em> option.</p></li>
       </ul>
      </p>
     </dd>

    
   </dl>

  </p>
 </div>


 <div class="refsect1 returnvalues" id="refsect1-mongocollection.insert-returnvalues">
  <h3 class="title">返回值</h3>
  <p class="para">
   如果设置了 <em>&quot;w&quot;</em> 选项，将会返回包含插入状态的数组。
   否则，将会返回一个 <strong><code>TRUE</code></strong> 代表数组不是空的（空数组将会抛出 <a href="class.mongoexception.html" class="classname">MongoException</a> ）。
  </p>
  <p class="para">
   如果返回了一个 array，将会有以下键：
   <dl>

    
     <dt>

      <em><code class="parameter">ok</code></em>
     </dt>

     <dd>

      <p class="para">
       它应该总是 1（除非 last_error 本身出现错误）。
      </p>
     </dd>

    
    
     <dt>

      <em><code class="parameter">err</code></em>
     </dt>

     <dd>

      <p class="para">
       如果这个字段不是 null，说明刚才的操作出现了错误。
       如果有这个字段，它将包含一个字符串，用于描述出现的错误信息。
      </p>
     </dd>

    
    
     <dt>

      <em><code class="parameter">code</code></em>
     </dt>

     <dd>

      <p class="para">
       如果发生了一个数据库错误，相应的错误码会传到客户端。
      </p>
     </dd>

    
    
     <dt>

      <em><code class="parameter">errmsg</code></em>
     </dt>

     <dd>

      <p class="para">
       如果数据库命令出现了错误，将会设置这个字段。同时 <em>ok</em> 也会是 0.
       例如，设置了 <em>w</em> 并且超时了，errmsg 将会是 &quot;timed
       out waiting for slaves&quot; 并且 <em>ok</em> 是 0。
       如果设置了这个字段，它会是发生的错误的字符串描述。 
      </p>
     </dd>

    
    
     <dt>

      <em><code class="parameter">n</code></em>
     </dt>

     <dd>

      <p class="para">
       如果最后的操作是插入、更新或删除，将会返回受影响的对象数量。对于插入操作，这个值总是 <em>0</em>。
      </p>
     </dd>

    
    
     <dt>

      <em><code class="parameter">wtimeout</code></em>
     </dt>

     <dd>

      <p class="para">
       等待复制直到超时的时间。
      </p>
     </dd>

    
    
     <dt>

      <em><code class="parameter">waited</code></em>
     </dt>

     <dd>

      <p class="para">
       在超时前，要等待操作多久。
      </p>
     </dd>

    
    
     <dt>

      <em><code class="parameter">wtime</code></em>
     </dt>

     <dd>

      <p class="para">
       如果设置了 <em>w</em> 并且操作成功了，等到复制到 <em>w</em> 台服务器的时间。 
      </p>
     </dd>

    
    
     <dt>

      <em><code class="parameter">upserted</code></em>
     </dt>

     <dd>

      <p class="para">
       如果发生了一次 upsert，这个字段将会包含新记录的
       <em>_id</em>。
       对于 upsert，不管是该字段还是
       <em>updatedExisting</em> 都会被保留（除非发生了一个错误）。
      </p>
     </dd>

    
    
     <dt>

      <em><code class="parameter">updatedExisting</code></em>
     </dt>

     <dd>

      <p class="para">
       如果一个 upsert 更新了一个存在的元素，这个字段将会是 true。
       对于 upsert，无论是这个字段 还是 upserted 都会被保留（除非发生了错误）。
      </p>
     </dd>

    
   </dl>

  </p>
 </div>


 <div class="refsect1 errors" id="refsect1-mongocollection.insert-errors">
  <h3 class="title">错误／异常</h3>
  <p class="para">
   如果插入的文档是空的，或者包含零长度的键，将会抛出 <a href="class.mongoexception.html" class="classname">MongoException</a>。
   尝试插入包含 protected 和 private 属性的对象将会导致零长度键（zero-length key）的错误。
  </p>
  <p class="para">Throws <a href="class.mongocursorexception.html" class="classname">MongoCursorException</a> if the &quot;w&quot; option is set and the write fails.</p><p class="para">Throws <a href="class.mongocursortimeoutexception.html" class="classname">MongoCursorTimeoutException</a> if the &quot;w&quot; option is set to a value greater than one and the operation takes longer than <var class="varname"><var class="varname">MongoCursor::$timeout</var></var> milliseconds to complete.  This does not kill the operation on the server, it is a client-side timeout. The operation in <em>MongoCollection::$wtimeout</em> is milliseconds.</p>
 </div>


 <div class="refsect1 changelog" id="refsect1-mongocollection.insert-changelog">
  <h3 class="title">更新日志</h3>
  <p class="para">
   <table class="doctable informaltable">
    
     <thead>
      <tr>
       <th>版本</th>
       <th>说明</th>
      </tr>

     </thead>

     <tbody class="tbody">
      <tr>
       <td>1.3.0</td>
       <td>
        <em><code class="parameter">options</code></em> 参数不再接受 boolean 来标识一个确认的写入。
        现在，你可以通过
        <em>array(&#039;w&#039; =&gt; 1)</em> 设置（
        <a href="class.mongoclient.html" class="classname">MongoClient</a> 默认的行为）
       </td>
      </tr>

      <tr>
       <td>1.2.0</td>
       <td>增加了 <em>&quot;timeout&quot;</em> 选项。</td>
      </tr>

      <tr>
       <td>1.0.11</td>
       <td>
        如果设置了 <em>&quot;safe&quot;</em>，出现 &quot;not master&quot; 错误时断开连接。
       </td>
      </tr>

      <tr>
       <td>1.0.9</td>
       <td>
        <p class="para">
         <em>&quot;safe&quot;</em> 选项接受 integer 值，之前只接受 boolean 值。
        </p>
        <p class="para">
         增加 <em>&quot;fsync&quot;</em> 选项。
        </p>
        <p class="para">
         如果设置了 <em>&quot;safe&quot;</em> 选项，返回类型改成包含错误信息的 array。
         否则，和之前一样返回 boolean。
        </p>
       </td>
      </tr>

      <tr>
       <td>1.0.5</td>
       <td>
        修改第二个参数为选项数组。在 1.0.5 之前，第二个参数是 boolean，指示 <em>&quot;safe&quot;</em> 选项。
       </td>
      </tr>

      <tr>
       <td>1.0.1</td>
       <td>
        如果设置了 <em>&quot;safe&quot;</em> 选项并且插入失败了，将会抛出 <a href="class.mongocursorexception.html" class="classname">MongoCursorException</a>。
       </td>
      </tr>

     </tbody>
    
   </table>

  </p>
 </div>


 <div class="refsect1 examples" id="refsect1-mongocollection.insert-examples">
  <h3 class="title">范例</h3>
  <div class="example" id="example-1432">
   <p><strong>Example #1 <span class="function"><strong>MongoCollection::insert()</strong></span> <em>_id</em> 例子</strong></p>
   <div class="example-contents"><p>
    如果没有 <em>_id</em>，则会添加一个到插入的文档中。
    基于参数传入的方式，在调用代码时可能无法产生有效
    <em>_id</em>。
   </p></div>
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /><br />$m&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">MongoClient</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">$collection&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$m</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">selectCollection</span><span style="color: #007700">(</span><span style="color: #DD0000">'test'</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">'phpmanual'</span><span style="color: #007700">);<br /></span><span style="color: #FF8000">//&nbsp;如果使用的是&nbsp;array&nbsp;字面语法，将无法成功生成&nbsp;_id<br /></span><span style="color: #0000BB">$collection</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">insert</span><span style="color: #007700">(array(</span><span style="color: #DD0000">'x'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">1</span><span style="color: #007700">));<br /><br /></span><span style="color: #FF8000">//&nbsp;通过传&nbsp;array&nbsp;的变量可以生成&nbsp;_id<br /></span><span style="color: #0000BB">$a&nbsp;</span><span style="color: #007700">=&nbsp;array(</span><span style="color: #DD0000">'x'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">2</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$collection</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">insert</span><span style="color: #007700">(</span><span style="color: #0000BB">$a</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$a</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">//&nbsp;通过传引用的&nbsp;array&nbsp;无法生成&nbsp;_id<br /></span><span style="color: #0000BB">$b&nbsp;</span><span style="color: #007700">=&nbsp;array(</span><span style="color: #DD0000">'x'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">3</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$ref&nbsp;</span><span style="color: #007700">=&nbsp;&amp;</span><span style="color: #0000BB">$b</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$collection</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">insert</span><span style="color: #007700">(</span><span style="color: #0000BB">$ref</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$ref</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">//&nbsp;没有在包裹的函数中触发&nbsp;copy-on-write&nbsp;时&nbsp;_id&nbsp;有效<br /></span><span style="color: #007700">function&nbsp;</span><span style="color: #0000BB">insert_no_cow</span><span style="color: #007700">(</span><span style="color: #0000BB">$collection</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$document</span><span style="color: #007700">)<br />{<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$collection</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">insert</span><span style="color: #007700">(</span><span style="color: #0000BB">$document</span><span style="color: #007700">);<br />}<br /><br /></span><span style="color: #0000BB">$c&nbsp;</span><span style="color: #007700">=&nbsp;array(</span><span style="color: #DD0000">'x'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">4</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">insert_no_cow</span><span style="color: #007700">(</span><span style="color: #0000BB">$collection</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$c</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$c</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">//&nbsp;在包裹的函数中触发&nbsp;copy-on-write&nbsp;时&nbsp;_id&nbsp;无效<br /></span><span style="color: #007700">function&nbsp;</span><span style="color: #0000BB">insert_cow</span><span style="color: #007700">(</span><span style="color: #0000BB">$collection</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$document</span><span style="color: #007700">)<br />{<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$document</span><span style="color: #007700">[</span><span style="color: #DD0000">'y'</span><span style="color: #007700">]&nbsp;=&nbsp;</span><span style="color: #0000BB">1</span><span style="color: #007700">;<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$collection</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">insert</span><span style="color: #007700">(</span><span style="color: #0000BB">$document</span><span style="color: #007700">);<br />}<br /><br /></span><span style="color: #0000BB">$d&nbsp;</span><span style="color: #007700">=&nbsp;array(</span><span style="color: #DD0000">'x'&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">5</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">insert_cow</span><span style="color: #007700">(</span><span style="color: #0000BB">$collection</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$d</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$d</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
   </div>

   <div class="example-contents"><p>以上例程的输出类似于：</p></div>
   <div class="example-contents screen">
<div class="cdata"><pre>
array(2) {
  [&quot;x&quot;]=&gt;
  int(2)
  [&quot;_id&quot;]=&gt;
  object(MongoId)#4 (0) {
  }
}
array(1) {
  [&quot;x&quot;]=&gt;
  int(3)
}
array(2) {
  [&quot;x&quot;]=&gt;
  int(4)
  [&quot;_id&quot;]=&gt;
  object(MongoId)#5 (0) {
  }
}
array(1) {
  [&quot;x&quot;]=&gt;
  int(5)
}
</pre></div>
   </div>
  </div>

  <div class="example" id="example-1433">
   <p><strong>Example #2 <span class="function"><strong>MongoCollection::insert()</strong></span> 确认写入的例子</strong></p>
   <div class="example-contents"><p>
    这个例子显示了设置了 <em><code class="parameter">w</code></em> 后，插入两个具有相同 _id 的元素时，导致抛出 <a href="class.mongocursorexception.html" class="classname">MongoCursorException</a> 的例子。
   </p></div>
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /><br />$person&nbsp;</span><span style="color: #007700">=&nbsp;array(</span><span style="color: #DD0000">"name"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #DD0000">"Joe"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"age"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">20</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$collection</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">insert</span><span style="color: #007700">(</span><span style="color: #0000BB">$person</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">//&nbsp;现在&nbsp;$person&nbsp;具有一个&nbsp;_id&nbsp;字段，所以我们再次&nbsp;<br />//&nbsp;保存它的时候，将会得到一个异常<br /></span><span style="color: #007700">try&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$collection</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">insert</span><span style="color: #007700">(</span><span style="color: #0000BB">$person</span><span style="color: #007700">,&nbsp;array(</span><span style="color: #DD0000">"w"&nbsp;</span><span style="color: #007700">=&gt;&nbsp;</span><span style="color: #0000BB">1</span><span style="color: #007700">));<br />}&nbsp;catch(</span><span style="color: #0000BB">MongoCursorException&nbsp;$e</span><span style="color: #007700">)&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;echo&nbsp;</span><span style="color: #DD0000">"Can't&nbsp;save&nbsp;the&nbsp;same&nbsp;person&nbsp;twice!\n"</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
   </div>

  </div>
 </div>


 <div class="refsect1 seealso" id="refsect1-mongocollection.insert-seealso">
  <h3 class="title">参见</h3>
  <ul class="simplelist">
   <li class="member"><span class="function"><a href="mongocollection.batchinsert.html" class="function" rel="rdfs-seeAlso">MongoCollection::batchInsert()</a> - Inserts multiple documents into this collection</span></li>
   <li class="member"><span class="function"><a href="mongocollection.update.html" class="function" rel="rdfs-seeAlso">MongoCollection::update()</a> - Update records based on a given criteria</span></li>
   <li class="member"><span class="function"><a href="mongocollection.find.html" class="function" rel="rdfs-seeAlso">MongoCollection::find()</a> - 查询该集合，并返回结果集的 MongoCursor</span></li>
   <li class="member"><span class="function"><a href="mongocollection.remove.html" class="function" rel="rdfs-seeAlso">MongoCollection::remove()</a> - 从集合中删除记录</span></li>
   <li class="member">MongoDB <a href="http://docs.mongodb.org/manual/tutorial/insert-documents/" class="link external">&raquo;&nbsp;insert</a> 的核心文档。</li>
  </ul>
 </div>


</div><hr /><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="mongocollection.group.html">MongoCollection::group</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="mongocollection.remove.html">MongoCollection::remove</a></div>
 <div class="up"><a href="class.mongocollection.html">MongoCollection</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
